home *** CD-ROM | disk | FTP | other *** search
/ Utilities Professional 1-1500 / Utilities Professional 1-1500 (1994)(WPD)[!].iso / 10011250 / var1219.dms / var1219.adf / ARexxGuide / ARx_Func.ag (.txt) < prev    next >
Amigaguide Document  |  1992-09-02  |  33KB  |  567 lines
  1. @DATABASE "ARx_Func.ag"
  2. @VER 1.0a
  3. @INDEX ARx_Index/MAIN
  4. @NODE MAIN "ARexxGuide | Functions Reference |"
  5. @TOC ARexxGuide.guide/MAIN
  6. @PREV ARx_Instr.ag/MAIN
  7. @NEXT ARx_Operator.ag/MAIN
  8.    @{FG HIGHLIGHT}AN AMIGAGUIDE
  9.  TO ARexx@{FG TEXT}                 Edition: 1.0a
  10.    by Robin Evans
  11.    @{" About this section         " link ABOUT}
  12.    ARexx functions:
  13.          @{" Comparison functions " link CMPRLIST} FIND(), POS(), ABBREV(), etc.
  14.          @{" String manipulation  " link STRLIST} LEFT(), SUBSTR(), etc.
  15.          @{" Word manipulation    " link ARx_Func2.ag/WORDLIST} WORD(), DELWORD(), etc.
  16.          @{" Char/Num translation " link ARx_Func2.ag/TRANLIST} C2D(), X2C(), D2X() etc.
  17.          @{" Number manipulation  " link ARx_Func2.ag/NUMLIST} RANDOM(), MAX(), etc.
  18.          @{" Informational        " link ARx_Func2.ag/INFOLIST} DATE(), SHOW(), etc.
  19.          @{" File input/output    " link ARx_Func3.ag/FILEIOLIST} OPEN(), READLN(), SEEK(), etc.
  20.          @{" File management      " link ARx_Func3.ag/FILEMGTLIST} DELETE(), EXISTS(), RENAME(), etc.
  21.          @{" ARexx control        " link ARx_Func3.ag/ARXLIST} ADDLIB(), PRAGMA(), etc.
  22.          @{" Message ports        " link ARx_Func4.ag/PORTLIST} OPENPORT(), WAITPKT(), GETARG(), etc.
  23.          @{" Memory management    " link ARx_Func4.ag/MEMLIST} IMPORT(), NEXT(), NULL(), etc.
  24.          @{" Bit-wise operations  " link ARx_Func4.ag/BITLIST} BITAND(), BITCMP(), etc.
  25.    @{" All functions  [INDEX ]    " link FUNCLIST}
  26.             Copyright 
  27.  1993, Robin Evans.  All rights reserved.
  28.     This guide is @{" shareware " link ArexxGuide.guide/REG}. If you find it useful, please register.
  29. @EndNode
  30. @Node ABOUT "ARexxGuide | Functions Reference | ABOUT"
  31. @PREV MAIN
  32.     @{FG HIGHLIGHT}REFERENCE TO BUILT-IN AND REXXSUPPORT.LIBRARY FUNCTIONS@{FG TEXT}
  33.     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  34. This section presents a reference to @{" built-in functions " link ARx_Elements3.ag/BLTFUNC} and to the
  35. functions included in @{" rexxsupport.library " link RXSPTLIB}.
  36. Each node begins with a template that shows the format of the arguments
  37. accepted by the function. The following conventions are used:
  38.    <>    A word or term surrounded by angle brackets should be replaced by
  39.          an expression. Any form of expression that returns a value of the
  40.          proper type may be used in place of this item. The replacement is
  41.          often a @{" variable " link ARx_Elements2.ag/VARIABLE}, but it could also be a literal value, an
  42.          @{" operation " link ARx_Elements3.ag/OPERATION}, or another function @{" call " link ARx_Instr.ag/CALL}.
  43.          The names used for the items in each template are included as
  44.          mnemonic devices -- terms that may help the user remember what
  45.          each expression stands for. They are not otherwise significant.
  46.          Each term is explained in more detail in the note following the
  47.          template.
  48.    []    Items enclosed in square brackets are optional. They may be
  49.          excluded when the function is called, but the commas that
  50.          separate optional items are significant. If only the second of
  51.          two optional items is included, a comma must still be used as a
  52.          placeholder for the omitted item as it is in the following:
  53.             SHOW('P',,'0a'x)
  54.    {}    Items enclosed in curly braces and entered in uppercase are
  55.          literal values. The expression used for such an argument must
  56.          return one of the values from the list.
  57.    |     A bar is used to separate a list of literal values within {}
  58.          braces.
  59.    <UC>  UPPERCASE characters are used to indicate literal values that may
  60.          be used as argument. The value may be entered in upper or
  61.          lowercase when the instruction is actually used. Only the first
  62.          letter of the option need be included. The value may be entered
  63.          as any type of @{" expression " link ARx_Elements2.ag/EXPRESSION}.
  64.    >>>   Three angle-braces are used in examples to indicate what the
  65.          example would output if run from a shell. Those braces and the
  66.          following text is not part of the code and should not be
  67.          entered if the example is used.
  68. Next: REXXSUPPORT.LIBRARY | Prev: Function ref. | Contents: Function ref.
  69. @EndNode
  70. @Node RXSPTLIB "ARexxGuide | Functions Reference | REXXSUPPORT.LIBRARY"
  71. @NEXT MAIN
  72. @{" Functions " link ARx_Elements3.ag/FUNCTION} can be added to ARexx by means of @{" external libraries " link ARx_Elements3.ag/EXTFUNC}. One
  73. such library is included with the distribution of ARexx. Called
  74. 'rexxsupport.library', it should be present in the user's libs: directory
  75. after ARexx is installed.
  76. The library adds several Amiga-specific functions that are not defined as
  77. a standard part of the REXX language. Included are memory-control
  78. functions like @{" ALLOCMEM() " link ARx_Func4.ag/ALLOCMEM()}, file system functions like @{" MAKEDIR() " link ARx_Func3.ag/MAKEDIR()}, and
  79. interprocess-communication functions like @{" OPENPORT() " link ARx_Func4.ag/OPENPORT()}.
  80. The functions in rexxsupport.library will not automatically be available
  81. to ARexx scripts, however. The are available only if the library is
  82. explicitly added to the list of libraries through which ARexx searches to
  83. find functions.
  84. That can be done with the @{" ADDLIB() " link ARx_Func3.ag/ADDLIB()} function or with the @{" RXLIB " link ARx_Cmd.ag/RXLIB} command
  85. utility. Examples of loading the library are included with the description
  86. of each of those methods.
  87. Frequent users of ARexx may wish to add rexxsupport.library to the system
  88. during the startup sequence.
  89. Next: Function ref. | Prev: About section | Contents: Function ref.
  90. @EndNode
  91. @Node FuncList "ARexxGuide | Functions reference | INDEX to built-in & support functions""
  92. @Next MAIN
  93. @PREV MAIN
  94. @{" ABBREV       " link ABBREV()} @{" ABS          " link ARx_Func2.ag/ABS()} @{" ADDRESS      " link ARx_Func3.ag/ADDRESS()} @{" ADDLIB       " link ARx_Func3.ag/ADDLIB()} @{" ALLOCMEM     " link ARx_Func4.ag/ALLOCMEM()}
  95. @{" ARG          " link ARx_Func3.ag/ARG()} @{" BADDR        " link ARx_Func4.ag/BADDR()} @{" B2C          " link ARx_Func2.ag/B2C()} @{" BITAND       " link ARx_Func4.ag/BITAND()} @{" BITCHG       " link ARx_Func4.ag/BITCHG()}
  96. @{" BITCLR       " link ARx_Func4.ag/BITCLR()} @{" BITCOMP      " link ARx_Func4.ag/BITCOMP()} @{" BITOR        " link ARx_Func4.ag/BITOR()} @{" BITSET       " link ARx_Func4.ag/BITSET()} @{" BITTST       " link ARx_Func4.ag/BITTST()}
  97. @{" BITXOR       " link ARx_Func4.ag/BITXOR()} @{" C2B          " link ARx_Func2.ag/C2B()} @{" C2D          " link ARx_Func2.ag/C2D()} @{" C2X          " link ARx_Func2.ag/C2X()} @{" CENTER       " link CENTER()}
  98. @{" CLOSE        " link ARx_Func3.ag/CLOSE()} @{" CLOSEPORT    " link ARx_Func4.ag/CLOSEPORT()} @{" COMPARE      " link COMPARE()} @{" COMPRESS     " link COMPRESS()} @{" COPIES       " link COPIES()}
  99. @{" D2C          " link ARx_Func2.ag/D2C()} @{" DATATYPE     " link ARx_Func3.ag/DATATYPE()} @{" DATE         " link ARx_Func2.ag/DATE()} @{" DELAY        " link ARx_Func3.ag/DELAY()} @{" DELETE       " link ARx_Func3.ag/DELETE()}
  100. @{" DELSTR       " link DELSTR()} @{" DELWORD      " link ARx_Func2.ag/DELWORD()} @{" DIGITS       " link ARx_Func3.ag/DIGITS()} @{" EOF          " link ARx_Func3.ag/EOF()} @{" ERRORTEXT    " link ARx_Func3.ag/ERRORTEXT()}
  101. @{" EXISTS       " link ARx_Func3.ag/EXISTS()} @{" EXPORT       " link ARx_Func4.ag/EXPORT()} @{" FIND         " link FIND()} @{" FORBID       " link ARx_Func4.ag/FORBID()} @{" FORM         " link ARx_Func3.ag/FORM()}
  102. @{" FREEMEM      " link ARx_Func4.ag/FREEMEM()} @{" FREESPACE    " link ARx_Func4.ag/FREESPACE()} @{" FUZZ         " link ARx_Func3.ag/FUZZ()} @{" GETARG       " link ARx_Func4.ag/GETARG()} @{" GETCLIP      " link ARx_Func3.ag/GETCLIP()}
  103. @{" GETPKT       " link ARx_Func4.ag/GETPKT()} @{" GETSPACE     " link ARx_Func4.ag/GETSPACE()} @{" HASH         " link ARx_Func2.ag/HASH()} @{" IMPORT       " link ARx_Func4.ag/IMPORT()} @{" INDEX        " link INDEX()}
  104. @{" INSERT       " link INSERT()} @{" LASTPOS      " link LASTPOS()} @{" LEFT         " link LEFT()} @{" LENGTH       " link LENGTH()} @{" LINES        " link ARx_Func3.ag/LINES()}
  105. @{" MAKEDIR      " link ARx_Func3.ag/MAKEDIR()} @{" MAX          " link ARx_Func2.ag/MAX()} @{" MIN          " link ARx_Func2.ag/MIN()} @{" NEXT         " link ARx_Func4.ag/NEXT()} @{" NULL         " link ARx_Func4.ag/NULL()}
  106. @{" OFFSET       " link ARx_Func4.ag/OFFSET()} @{" OPEN         " link ARx_Func3.ag/OPEN()} @{" OPENPORT     " link ARx_Func4.ag/OPENPORT()} @{" OVERLAY      " link OVERLAY()} @{" PERMIT       " link ARx_Func4.ag/PERMIT()}
  107. @{" POS          " link POS()} @{" PRAGMA       " link ARx_Func3.ag/PRAGMA()} @{" RANDOM       " link ARx_Func2.ag/RANDOM()} @{" RANDU        " link ARx_Func2.ag/RANDU()} @{" READCH       " link ARx_Func3.ag/READCH()}
  108. @{" READLN       " link ARx_Func3.ag/READLN()} @{" REMLIB       " link ARx_Func3.ag/REMLIB()} @{" RENAME       " link ARx_Func3.ag/RENAME()} @{" REPLY        " link ARx_Func4.ag/REPLY()} @{" REVERSE      " link REVERSE()}
  109. @{" RIGHT        " link RIGHT()} @{" SEEK         " link ARx_Func3.ag/SEEK()} @{" SETCLIP      " link ARx_Func3.ag/SETCLIP()} @{" SHOW         " link ARx_Func2.ag/SHOW()} @{" SHOWDIR      " link ARx_Func2.ag/SHOWDIR()}
  110. @{" SHOWLIST     " link ARx_Func2.ag/SHOWLIST()} @{" SIGN         " link ARx_Func2.ag/SIGN()} @{" SOURCELINE   " link ARx_Func3.ag/SOURCELINE()} @{" SPACE        " link ARx_Func2.ag/SPACE()} @{" STATEF       " link ARx_Func3.ag/STATEF()}
  111. @{" STORAGE      " link ARx_Func4.ag/STORAGE()} @{" STRIP        " link STRIP()} @{" SUBSTR       " link SUBSTR()} @{" SUBWORD      " link ARx_Func2.ag/SUBWORD()} @{" SYMBOL       " link ARx_Func3.ag/SYMBOL()}
  112. @{" TIME         " link ARx_Func2.ag/TIME()} @{" TRACE        " link ARx_Func3.ag/TRACE()} @{" TRANSLATE    " link TRANSLATE()} @{" TRIM         " link TRIM()} @{" TRUNC        " link ARx_Func2.ag/TRUNC()}
  113. @{" TYPEPKT      " link ARx_Func4.ag/TYPEPKT()} @{" UPPER        " link UPPER()} @{" VALUE        " link ARx_Func3.ag/VALUE()} @{" VERIFY       " link VERIFY()} @{" WAITPKT      " link ARx_Func4.ag/WAITPKT()}
  114. @{" WORD         " link ARx_Func2.ag/WORD()} @{" WORDINDEX    " link ARx_Func2.ag/WORDINDEX()} @{" WORDLENGTH   " link ARx_Func2.ag/WORDLENGTH()} @{" WORDS        " link ARx_Func2.ag/WORDS()} @{" WRITECH      " link ARx_Func3.ag/WRITECH()}
  115. @{" WRITELN      " link ARx_Func3.ag/WRITELN()} @{" X2C          " link ARx_Func2.ag/X2C()} @{" XRANGE       " link XRANGE()}
  116. @EndNode
  117. @Node CMPRLIST "ARexxGuide | Functions reference (1 of 12) | COMPARISON"
  118. @Prev MAIN
  119. @NEXT STRLIST
  120.    @{" ABBREV    " link ABBREV()}(<longstring>,<shortstring>,[<length>])
  121.    @{" COMPARE   " link COMPARE()}(<string1>,<string2>,[<padchar>])
  122.    @{" FIND      " link FIND()}(<haystack>, <needle>)
  123.    @{" INDEX     " link INDEX()}(<haystack>,<needle>, [<startpos>])
  124.    @{" LASTPOS   " link LASTPOS()}(<needle>,<haystack>,[<startpos>])
  125.    @{" POS       " link POS()}(<needle>,<haystack>,[<startpos>])
  126.    @{" VERIFY    " link VERIFY()}(<string>, <reference>, [{'NOMATCH'|'MATCH'}], [<startpos>])
  127. Related functions:
  128.    @{" BITCOMP   " link ARx_Func4.ag/BITCOMP()}
  129.    @{" BITTST    " link ARx_Func4.ag/BITTST()}
  130.    @{" DATATYPE  " link ARx_Func3.ag/DATATYPE()}
  131.                      Also see @{" Bit manipulation functions   " link ARx_Func4.ag/BITLIST}
  132. Comparisons of one type or another are one of the most frequent tasks of
  133. any program. Comparisons allow a program to branch off to different code
  134. based on different conditions. @{" Comparison operators " link ARx_Operator.ag/COMPARISON} give ARexx the
  135. standard tools for matching strings, but these functions extend the power
  136. of the operators, allowing quick checks for a substring (what @{" Cowlishaw " link ARx_Intro.ag/REF}
  137. so elegantly calls a 'needle') in a string (the 'haystack'), or for a word
  138. of phrase within a string of words.
  139. Next: String functions | Prev: BITXOR() | Contents: Function reference
  140. @EndNode
  141. @Node ABBREV() "ARexxGuide | Functions reference | Comparison (1 of 7) | ABBREV"
  142. @TOC CMPRLIST
  143. @Prev CMPRLIST
  144. ABBREV(<longstring>,<shortstring>,[<length>])
  145.       returns boolean value
  146. Returns 1 if <shortstring> is equal to the leading characters of
  147. <longstring>. If <length> is specified, then <shortstring> must also be at
  148. least that long. The comparison is case-sensitive. If <length> is not
  149. specified, an empty string will always match <longstring>.
  150.       Returns 0 if either condition is not met.
  151.    Examples:
  152.          say abbrev('Waldorf','Waldo');              >>> 1
  153.          say abbrev('Waldorf','WALDO');              >>> 0
  154.          say abbrev(@{" upper('Waldorf') "link UPPER()}, 'WALDO');    >>> 1
  155.    Also see @{ " COMPARE       " link COMPARE()}
  156.             @{ " LEFT          " link LEFT()}
  157. Next: COMPARE() | Prev: Comparison func. | Contents: Comparison func.
  158. @EndNode
  159. @Node COMPARE() "ARexxGuide | Functions reference | Comparison (2 of 7) | COMPARE"
  160. @TOC CMPRLIST
  161. COMPARE(<string1>,<string2>,[<padchar>])
  162.       returns a number
  163. The result is 0 if both strings are identical. If they aren't, the number
  164. returned is the position of the first character where the strings differ.
  165. The shorter string is padded with <padchar> before the comparison.
  166. The default pad character is a blank.
  167.    Examples:
  168.          say compare('The first','The only');      >>> 5
  169.          say compare('worldwide','wordwide');      >>> 4
  170.          say compare('foo','f');                   >>> 2
  171.          say compare('foo','f','o');               >>> 0
  172.    Also see @{ " ABBREV        " link ABBREV()}
  173.             @{ " VERIFY        " link VERIFY()}
  174. Next: FIND() | Prev: ABBREV() | Contents: Comparison functions
  175. @EndNode
  176. @Node FIND() "ARexxGuide | Functions reference | Comparison (3 of 7) | FIND"
  177. @TOC CMPRLIST
  178. FIND(<haystack>, <needle>)
  179.       returns a number
  180. Locates the blank-delimited word or words <needle> within the string
  181. <haystack> and returns the word position of the first match, or 0 if there
  182. is no match.
  183. The search is case sensitive.
  184.    Examples:
  185.          say find('Tied to Godot?','dot');      >>> 0
  186.          say find('Tied to Godot?','to');       >>> 2
  187.    Also see @{ " INDEX         " link INDEX()}
  188.             @{ " POS           " link POS()}
  189.             @{ " WORDINDEX     " link ARx_Func2.ag/WORDINDEX()}
  190. In some implementations of REXX, this function is called WORDPOS() and
  191. takes arguments in the reverse order.
  192. Next: INDEX() | Prev: COMPARE() | Contents: Comparison functions
  193. @EndNode
  194. @Node INDEX() "ARexxGuide | Functions reference | Comparison (4 of 7) | INDEX"
  195. @TOC CMPRLIST
  196. INDEX(<haystack>,<needle>, [<startpos>])
  197.       returns a number
  198. The result is the character position within the string <haystack> of the
  199. the first occurrence of the string <needle> or 0 if a match isn't found.
  200. If <startpos> is specified, then the search proceeds from that position in
  201. <haystack>.
  202. The search is case sensitive.
  203.    Examples:
  204.          say index('Tied to Godot?','dot');      >>> 11
  205.          say index('Tied to Godot?','to');       >>> 6
  206.    Also see @{ " FIND          " link FIND()}
  207.             @{ " POS           " link POS()}
  208. Next: LASTPOS() | Prev: FIND() | Contents: Comparison functions
  209. @EndNode
  210. @Node LASTPOS() "ARexxGuide | Functions reference | Comparison (5 of 7) | LASTPOS"
  211. @TOC CMPRLIST
  212. LASTPOS(<needle>,<haystack>,[<startpos>])
  213.       returns a number
  214. The result is the character position within the string <haystack> of the
  215. the last occurrence of the string <needle> or 0 if a match isn't found.
  216. If <startpos> is specified, then the search proceeds backwards from that
  217. position in <haystack>.
  218.    Examples:
  219.          say lastpos('eak','growing weaker and weaker');    >>> 21
  220.          say lastpos('eak','growing weaker and weaker',20); >>> 10
  221.    Also see @{ " POS           " link POS()}
  222.                                  @{" NOTE: Extracting file names       " alink ARx_Notes.ag/FILENAME}
  223. Next: POS() | Prev: INDEX() | Contents: Comparison functions
  224. @EndNode
  225. @Node POS() "ARexxGuide | Functions reference | Comparison (6 of 7) | POS"
  226. @TOC CMPRLIST
  227. POS(<needle>,<haystack>,[<startpos>])
  228.       returns a number
  229. The result is the character position within the string <haystack> of the
  230. the first occurrence of the string <needle> or 0 if a match isn't found.
  231. If <startpos> is specified, then the search proceeds forward from that
  232. position in <haystack>.
  233. The search is case sensitive.
  234.    Examples:
  235.          say pos('eak','growing weaker and weaker')     >>> 10
  236.          say pos('eak','growing weaker and weaker',11)  >>> 21
  237.    Also see @{ " LASTPOS       " link LASTPOS()}
  238.             @{ " VERIFY        " link VERIFY()}
  239. Next: VERIFY() | Prev: LASTPOS() | Contents: Comparison functions
  240. @EndNode
  241. @Node VERIFY() "ARexxGuide | Functions reference | Comparison (7 of 7) | VERIFY"
  242. @TOC CMPRLIST
  243. @Next CMPRLIST
  244. VERIFY(<string>, <reference>, ['MATCH'], [<startpos>])
  245.       returns a number
  246. Checks for the presence in <string> of any characters that appear in
  247. <reference> -- a list of characters which may be entered in any order.
  248. If the 'MATCH' option is omitted, the functions returns 0 when all
  249. characters in <string> are contained in <reference>. Otherwise, the number
  250. returned is the position of the first character in <string> that does not
  251. match a character in <reference>.
  252. The 'M' (match) option will cause the function to return the position of
  253. the first character in <string> that matches a character in <reference>.
  254. It returns 0 if none of the characters in <string> match a character in
  255. <reference>. It can be used to verify that invalid characters are not used
  256. in <string> or to check for the position of the first of a range of
  257. characters.
  258. If <startpos> is specified, the search will begin at that character
  259. position in <string>.
  260.    Examples:
  261.          say verify('#789-ABD', '1234567890ABCD-#')   >>> 0
  262.          say verify('#432-cfo', '1234567890ABCD-#')   >>> 6
  263.          say verify('FileName', ':;*/?`#%', 'm')      >>> 0
  264.          say verify('File*NAME', ':;*/?`#%', 'm')     >>> 5
  265.          say verify('File*NAME', ':;*/?`#%', 'm',6)   >>> 0
  266.          say verify('t:foo/file', ':/', 'm')          >>> 2
  267.    Also see @{ " DATATYPE      " link ARx_Func3.ag/DATATYPE()}
  268.             @{ " POS           " link POS()}
  269.                                  @{" NOTE: Checking unique datatypes   " alink ARx_Notes.ag/VERIFYNOTE}
  270. Next: Comparison functions | Prev: POS() | Contents: Comparison functions
  271. @EndNode
  272. @Node STRLIST  "ARexxGuide | Functions reference (2 of 12) | STRING MANIPULATION"
  273. @PREV CMPRLIST
  274. @NEXT ARx_Func2.ag/WORDLIST
  275.    @{" CENTER    " link CENTER()}(<string>,<length>,[<padchar>])
  276.    @{" COMPRESS  " link COMPRESS()}(<string>, [<list>])
  277.    @{" COPIES    " link COPIES()}(<string>,<number>)
  278.    @{" DELSTR    " link DELSTR()}(<string>,<number>, [<length>])
  279.    @{" INSERT    " link INSERT()}(<new string>, <old string>,<startpos>, [<length>],[<padchar>])
  280.    @{" LEFT      " link LEFT()}(<string>,<length>,[<padchar>])
  281.    @{" LENGTH    " link LENGTH()}(<string>)
  282.    @{" OVERLAY   " link OVERLAY()}(<new string>, <old string>,[<startpos>], [<length>],[<padchar>])
  283.    @{" REVERSE   " link REVERSE()}(<string>)
  284.    @{" RIGHT     " link RIGHT()}(<string>,<length>,[<padchar>])
  285.    @{" STRIP     " link STRIP()}(<string>, [{'B'|'L'|'T'}], [<list>])
  286.    @{" SUBSTR    " link SUBSTR()}(<string>, <startpos>, [<length>],[<padchar>])
  287.    @{" TRANSLATE " link TRANSLATE()}(<string>,[<output table>], [<input table>],[<padchar>])
  288.    @{" TRIM      " link TRIM()}(<string>)
  289.    @{" UPPER     " link UPPER()}(<string>)
  290.    @{" XRANGE    " link XRANGE()}([<start>, [<end>])
  291.                      Also see @{" Word manipulation functions  " link ARx_Func2.ag/WORDLIST}
  292.                               @{" Number manipulation functions" link ARx_Func2.ag/NUMLIST}
  293.                               @{" PARSE instruction            " link ARx_Instr2.ag/PARSE}
  294. Nearly any change one might contemplate for a string can be made with one,
  295. or a combination of these functions, or one of the closely-allied
  296. @{" word manipulation functions " link ARx_Func2.ag/WORDLIST}. They'll cut chunks out of a string --
  297. LEFT(), RIGHT(), SUBSTR(), DELSTR(); or remove only certain characters --
  298. STRIP(), TRIM(), COMPRESS(); or add to the string -- OVERLAY(), INSERT(),
  299. COPIES(), CENTER(); or transform it in subtle and wonderful ways --
  300. TRANSLATE(), REVERSE().
  301. Next: Word functions | Prev: FuncList | Contents: Function reference
  302. @EndNode
  303. @Node CENTER() "ARexxGuide | Functions reference | String (1 of 15) | CENTER"
  304. @TOC STRLIST
  305. @PREV STRLIST
  306. CENTER(<string>,<length>,[<padchar>])
  307.       returns a string
  308. The result is a string of <length> characters with <string> centered in
  309. it. The <padchar> is used to fill out the left and right sides of the
  310. string. The default pad character is a blank.
  311.    Example:
  312.          say '['center('Title',20)']';      >>> [       Title        ]
  313.          say center('Title',22,'*');        >>> ********Title*********
  314.    Also see @{ " SPACE         " link ARx_Func2.ag/SPACE()}
  315.             @{ " COPIES        " link COPIES()}
  316. Next: COMPRESS() | Prev: String functions | Contents: String functions
  317. @EndNode
  318. @Node COMPRESS() "ARexxGuide | Functions reference | String (2 of 15) | COMPRESS"
  319. @TOC STRLIST
  320. COMPRESS(<string>, [<list>])
  321.       returns a string
  322. Removes any of the characters contained in <list> from <string>. The
  323. default character for <list> is a blank, so this function will remove all
  324. blanks if only <string> is specified.
  325.    Examples:
  326.          say compress('$1,045','$,%');      >>> 1045
  327.          say compress('Call me Ismael.');   >>> CallmeIsmael.
  328.    Also see @{ " TRANSLATE     " link TRANSLATE()}
  329.             @{ " STRIP         " link STRIP()}
  330.             @{ " SPACE         " link ARx_Func2.ag/SPACE()}
  331.                                  @{" NOTE: Counting characters with COMPRESS() " alink ARx_Notes.ag/COUNTCHAR}
  332. Next: COPIES() | Prev: CENTER() | Contents: String functions
  333. @EndNode
  334. @Node COPIES() "ARexxGuide | Functions reference | String (3 of 15) | COPIES"
  335. @TOC STRLIST
  336. COPIES(<string>,<number>)
  337.       returns a string
  338. The result is a new string composed of <string> concatenated with itself
  339. <number> times.
  340.    Example:
  341.          say copies('xo',6);                >>> xoxoxoxoxoxo
  342.    Also see @{ " XRANGE        " link XRANGE()}
  343.             @{ " CENTER        " link CENTER()}
  344. Next: DELSTR() | Prev: COMPRESS() | Contents: String functions
  345. @EndNode
  346. @Node DELSTR() "ARexxGuide | Functions reference | String (4 of 15) | DELSTR"
  347. @TOC STRLIST
  348. DELSTR(<string>,<number>, [<length>])
  349.       returns a string
  350. Deletes a portion of <string> of <length> characters beginning at the
  351. <number> character position. The new string is returned. If <number> is
  352. greater than the length of <string> then <string> is returned unchanged.
  353. If <length> is omitted, all characters beginning at position <number> are
  354. deleted.
  355.    Example:
  356.          say delstr('indifference',3,3);      >>> inference
  357.    Also see @{ " DELWORD       " link ARx_Func2.ag/DELWORD()}
  358.             @{ " RIGHT         " link RIGHT()}
  359.             @{ " SUBSTR        " link SUBSTR()}
  360.             @{ " INSERT        " link INSERT()}
  361.             @{ " OVERLAY       " link OVERLAY()}
  362. Next: INSERT() | Prev: COPIES() | Contents: String functions
  363. @EndNode
  364. @Node INSERT() "ARexxGuide | Functions reference | String (5 of 15) | INSERT"
  365. @TOC STRLIST
  366. INSERT(<new string>, <old string>,<startpos>, [<length>],[<padchar>])
  367.       returns a string
  368. <new string> is inserted into <old string> beginning at <startpos>, the
  369. character-count position. <new string> will be padded with <padchar> or
  370. truncated to <length> characters.
  371. If <startpos> is greater than the length of <old string> then <padchar>
  372. will be added to the end of <old string> before the new string is added.
  373. If <startpos> is 0, then <new string> will be padded to <length> and then
  374. added to the start of <old string>
  375. The default length is the length of <new string>. The default pad
  376. character is a blank.
  377.    Example:
  378.          say insert('always behaved like','I have a pig.',7,20)
  379.                                  >>> I have always behaved like a pig.
  380.    Also see @{ " OVERLAY       " link OVERLAY()}
  381.             @{ " DELSTR        " link DELSTR()}
  382. Next: LEFT() | Prev: DELSTR() | Contents: String functions
  383. @EndNode
  384. @Node LEFT() "ARexxGuide | Functions reference | String (6 of 15) | LEFT"
  385. @TOC STRLIST
  386. LEFT(<string>,<length>,[<padchar>])
  387.       returns a string
  388. The result is a string of <length> characters made up of the leftmost
  389. characters in <string>. If <length> is greater than the length of
  390. <string>, then the string returned is filled out on the right with
  391. <padchar> -- a quick way to left-justify a string.
  392. The default pad character is a blank.
  393.    Example:
  394.          say left('never to stop saying',13);      >>> never to stop
  395.          say left('Widget', 12)'|'                 >>> Widget      |
  396.          say left('No', 4, '!')                    >>> No!!
  397.    Also see @{ " RIGHT         " link RIGHT()}
  398.             @{ " SUBSTR        " link SUBSTR()}
  399.             @{ " ABBREV        " link ABBREV()}
  400.                                  @{" NOTE: Formatting tables           " alink ARx_Notes.ag/FORMATNOTE}
  401. Next: LENGTH() | Prev: INSERT() | Contents: String functions
  402. @EndNode
  403. @Node LENGTH() "ARexxGuide | Functions reference | String (7 of 15) | LENGTH"
  404. @TOC STRLIST
  405. LENGTH(<string>)
  406.       returns a number
  407. The result is the number of characters in <string>.
  408.    Example:
  409.          say length('never to stop saying');      >>> 20
  410.                                  @{" NOTE: Counting characters with COMPRESS() " alink ARx_Notes.ag/COUNTCHAR}
  411. Next: OVERLAY() | Prev: LEFT() | Contents: String functions
  412. @EndNode
  413. @Node OVERLAY() "ARexxGuide | Functions reference | String (8 of 15) | OVERLAY"
  414. @TOC STRLIST
  415. OVERLAY(<new string>, <old string>,[<startpos>], [<length>],[<padchar>])
  416.       returns a string
  417. Replaces the characters of <old string> starting at position <startpos>
  418. with the characters of <new string>. The default starting position is the
  419. beginning of <old string>.
  420. If <length> is not specified, all of the characters from <new string> will
  421. be overlaid on <old string>. If a <length> is specified, then <new string>
  422. will either be truncated to that length or expanded to <length> using
  423. <padchar> to fill out the string.
  424. The default pad character is a blank.
  425.    Examples:
  426.          say overlay('12', 'abcdefg', 3, 4, '*')   >>> ab12**g
  427.          say overlay('abc', '12345678', 4, 2)      >>> 123ab678
  428.          say overlay( 'think of it',,
  429.            'the less I concentrate the more certain I am', 12)
  430.                      >>> the less I think of it the more certain I am
  431.    Also see @{ " INSERT        " link INSERT()}
  432.             @{ " DELSTR        " link DELSTR()}
  433. Note that the third example above uses the comma @{" continuation character " link ARx_Elements.ag/COMMA}
  434. to turn two lines of text into one program line.
  435. Next: REVERSE() | Prev: LENGTH() | Contents: String functions
  436. @EndNode
  437. @Node REVERSE() "ARexxGuide | Functions reference | String (9 of 15) | REVERSE"
  438. @TOC STRLIST
  439. REVERSE(<string>)
  440.       returns a string
  441. The result is <string> flipped end for end.
  442.    Example:
  443.          say reverse('chameleon');      >>> noelemahc
  444.    Also see @{ " LASTPOS       " link LASTPOS()}
  445. Next: RIGHT() | Prev: OVERLAY() | Contents: String functions
  446. @EndNode
  447. @Node RIGHT() "ARexxGuide | Functions reference | String (10 of 15) | RIGHT"
  448. @TOC STRLIST
  449. RIGHT(<string>,<length>,[<padchar>])
  450.       returns a string
  451. The result is a string of <length> characters made up the rightmost
  452. characters in <string>. If <length> is greater than the length of
  453. <string>, then the result is filled out on the left with <padchar> -- a
  454. quick way to right-justify a string.
  455. The default pad character is a blank.
  456.    Example:
  457.          say right('never to stop saying',11);      >>> stop saying
  458.          say '$'right(4.50, 6)                      >>> $  4.50
  459.          say '$'right(123.99, 6)                    >>> $123.99
  460.          say right('Whoa', 6, 'W')                  >>> WWWhoa
  461.    Also see @{ " LEFT          " link LEFT()}
  462.             @{ " SUBSTR        " link SUBSTR()}
  463.             @{ " DELSTR        " link DELSTR()}
  464.                                  @{" NOTE: Formatting tables           " alink ARx_Notes.ag/FORMATNOTE}
  465. Next: STRIP() | Prev: REVERSE() | Contents: String functions
  466. @EndNode
  467. @Node STRIP() "ARexxGuide | Functions reference | String (11 of 15) | STRIP"
  468. @TOC STRLIST
  469. STRIP(<string>, [{'B'|'L'|'T'}], [<list>])
  470.       returns a string
  471. Removes spaces (by default) or any character in <list> from the leading,
  472. trailing, or both ends (specified by the option used as the second
  473. argument) of <string>. The default option is 'B'.
  474.    Example:
  475.          say '|'strip('   understand   ')'|';         >>> |understand|
  476.          say '|'strip('   understand   ',L)'|';       >>> |understand   |
  477.          say '|'strip('___understand___',T,'_')'|';   >>> |___understand|
  478.          say strip('understand',,'dnu')               >>> ersta
  479.    Also see @{ " COMPRESS      " link COMPRESS()}
  480.             @{ " TRIM          " link TRIM()}
  481. The examples above use the abuttal @{" concatenation operator " link ARx_Operator.ag/CONCATENATION} to add the
  482. character '|' to the beginning and end of the string returned by STRIP().
  483. Next: SUBSTR() | Prev: RIGHT() | Contents: String functions
  484. @EndNode
  485. @Node SUBSTR() "ARexxGuide | Functions reference | String (12 of 15) | SUBSTR"
  486. @TOC STRLIST
  487. SUBSTR(<string>, <startpos>, [<length>],[<padchar>])
  488.       returns a string
  489. The result is a string of <length> characters made up the characters in
  490. <string> beginning at <startpos>.
  491. If <length> is not specified, then all of the string to the right of
  492. <startpos> will be returned. If the argument is specified, the returned
  493. string will have <length> characters, filled out, if necessary, with
  494. <padchar>.
  495. The default pad character is a blank.
  496.    Example:
  497.          say substr('indifference',3,3);      >>> dif
  498.          say substr('No way',4,5,'!')         >>> way!!
  499.    Also see @{ " LEFT          " link LEFT()}
  500.             @{ " RIGHT         " link RIGHT()}
  501.             @{ " DELSTR        " link DELSTR()}
  502.             @{ " SUBWORD       " link ARx_Func2.ag/SUBWORD()}
  503.             @{ " TRUNC         " link ARx_Func2.ag/TRUNC()}
  504. Next: TRANSLATE() | Prev: STRIP() | Contents: String functions
  505. @EndNode
  506. @Node TRANSLATE() "ARexxGuide | Functions reference | String (13 of 15) | TRANSLATE"
  507. @TOC STRLIST
  508. TRANSLATE(<string>,[<output table>], [<input table>],[<padchar>])
  509.       returns a string
  510. Any character in <string> that also appears in the <input table> is
  511. converted to the corresponding character in the <output table> or to the
  512. <padchar> if there isn't a corresponding character in the <output table>.
  513. If neither table is supplied, then the <string> is converted to upper
  514. case, just as it would be by @{" UPPER(<string>) " link UPPER()}.
  515. The default pad character is a blank.
  516.    Examples:
  517.          say translate('abcdef', '123456', 'abcdef')   >>> 123456
  518.          say translate('abcdef', '123456', 'defabc')   >>> 456123
  519.          say translate('abcdef', '1234', 'defabc','*') >>> 4**123
  520.          say translate('UNNAMABLE', xrange('a','z'), xrange('A','Z'))
  521.                                                        >>> unnamable
  522.    Also see @{ " COMPRESS      " link COMPRESS()}
  523. Next: TRIM() | Prev: SUBSTR() | Contents: String functions
  524. @EndNode
  525. @Node TRIM() "ARexxGuide | Functions reference | String (14 of 15) | TRIM"
  526. @TOC STRLIST
  527. TRIM(<string>)
  528.       returns a string
  529. The result is <string> with the trailing blanks removed.
  530.    Example:
  531.          say '|'trim('   understand   ')'|';    >>> |   understand|
  532.    Also see @{ " STRIP         " link STRIP()}
  533. Next: UPPER() | Prev: TRANSLATE() | Contents: String functions
  534. @EndNode
  535. @Node UPPER() "ARexxGuide | Functions reference | String (15 of 15) | UPPER"
  536. @TOC STRLIST
  537. UPPER(<string>)
  538.       returns a string
  539. The result is <string> translated to all uppercase characters.
  540.    Example:
  541.          say upper('Waldorf')       >>> WALDORF
  542.    Also see @{ " TRANSLATE     " link TRANSLATE()}
  543.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  544. A <string> can be translated to lowercase with the following function:
  545.    TRANSLATE(<string>, xrange('a', 'z'), xrange('A','Z'))
  546. The function @{" BITOR(<string>) " link ARx_Func4.ag/BITOR()} will also translate the alphabetic
  547. characters in <string> to lowercase characters, but it will shift the
  548. ASCII characters between 91 and 95 { [ \ ] ^ _} to characters 123 through
  549. Next: String functions | Prev: XRANGE() | Contents: String functions
  550. @EndNode
  551. @Node XRANGE() "ARexxGuide | Functions reference | Number (9 of 9) | XRANGE"
  552. @TOC STRLIST
  553. @NEXT STRLIST
  554. XRANGE([<start>, [<end>])
  555.       returns a string
  556. The result is a string comprised of all the characters between and
  557. including <start> and <end>.
  558. The output of the function is a character string. Use the @{" c2x() " link ARx_Func2.ag/C2X()}
  559. function, for example, to convert the output to hexadecimal number format.
  560.    Examples:
  561.          say xrange('a','g');              >>> abcdefg
  562.          say xrange(1,8);                  >>> 12345678
  563.          say c2x(xrange('c'x,'14'x));      >>> 0C0D0E0F1011121314
  564.    Also see @{ " COPIES        " link COPIES()}
  565. Next: String functions | Prev: UPPER() | Contents: String functions
  566. @EndNode
  567.